Skip to main content

Upgrading to v1.6

dbt Core v1.6 has three significant areas of focus:

  1. Next milestone of multi-project deployments: improvements to contracts, groups/access, versions; and building blocks for cross-project ref
  2. Semantic layer re-launch: dbt Core and MetricFlow integration
  3. Mechanisms to support mature deployment at scale (dbt clone and dbt retry)

Resources​

What to know before upgrading​

dbt Labs is committed to providing backward compatibility for all versions 1.x, with the exception of any changes explicitly mentioned below. If you encounter an error upon upgrading, please let us know by opening an issue.

Behavior changes​

Action required if your project defines metrics

The spec for metrics has changed and now uses MetricFlow.

If your dbt project defines metrics, you must migrate to dbt v1.6 because the YAML spec has moved from dbt_metrics to MetricFlow. Any tests you have won't compile on v1.5 or older.

  • dbt Core v1.6 does not support Python 3.7, which reached End Of Life on June 23. Support Python versions are 3.8, 3.9, 3.10, and 3.11.
  • As part of the dbt Semantic layer re-launch (in beta), the spec for metrics has changed significantly. Refer to the migration guide for more info on how to migrate to the re-launched dbt Semantic Layer.
  • The manifest schema version is now v10.
  • dbt Labs is ending support for Homebrew installation of dbt Core and adapters. See the discussion for more details.

For consumers of dbt artifacts (metadata)​

The manifest schema version has been updated to v10. Specific changes:

  • Addition of semantic_models and changes to metrics attributes
  • Addition of deprecation_date as a model property
  • Addition of on_configuration_change as default node configuration (to support materialized views)
  • Small type changes to contracts and constraints
  • Manifest metadata includes project_name

For maintainers of adapter plugins​

For more detailed information and to ask questions, please read and comment on the GH discussion: dbt-labs/dbt Core#7958.

New and changed documentation​

MetricFlow​

  • Build your metrics with MetricFlow, a key component of the Semantic Layer. You can define your metrics and build semantic models with MetricFlow, available on the command line (CLI) for dbt Core v1.6 beta or higher.

Materialized views​

Supported on:

New commands for mature deployment​

dbt retry executes the previously run command from the point of failure. Rebuild just the nodes that errored or skipped in a previous run/build/test, rather than starting over from scratch.

dbt clone leverages each data platform's functionality for creating lightweight copies of dbt models from one environment into another. Useful when quickly spinning up a new development environment, or promoting specific models from a staging environment into production.

Multi-project collaboration​

Deprecation date: Models can declare a deprecation date that will warn model producers and downstream consumers. This enables clear migration windows for versioned models, and provides a mechanism to facilitate removal of immature or little-used models, helping to avoid project bloat.

Model names can be duplicated across different namespaces (projects/packages), so long as they are unique within each project/package. We strongly encourage using two-argument ref when referencing a model from a different package/project.

More consistency and flexibility around packages. Resources defined in a package will respect variable and global macro definitions within the scope of that package.

  • vars defined in a package's dbt_project.yml are now available in the resolution order when compiling nodes in that package, though CLI --vars and the root project's vars will still take precedence. See "Variable Precedence" for details.
  • generate_x_name macros (defining custom rules for database, schema, alias naming) follow the same pattern as other "global" macros for package-scoped overrides. See macro dispatch for an overview of the patterns that are possible.
Closed Beta - dbt Enterprise

Project dependencies: Introduces dependencies.yml and dependent projects as a feature of dbt Enterprise. Allows enforcing model access (public vs. protected/private) across project/package boundaries. Enables cross-project ref of public models, without requiring the installation of upstream source code.

Deprecated functionality​

The ability for installed packages to override built-in materializations without explicit opt-in from the user is being deprecated.

  • Overriding a built-in materialization from an installed package raises a deprecation warning.

  • Using a custom materialization from an installed package does not raise a deprecation warning.

  • Using a built-in materialization package override from the root project via a wrapping materialization is still supported. For example:

    {% materialization view, default %}
    {{ return(my_cool_package.materialization_view_default()) }}
    {% endmaterialization %}

Quick hits​

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Edit this page